.TH PSP 8 "6 June 2005" "iproute2" "Linux"
.SH NAME
PSP \- Precise Software Pacer
.SH SYNOPSIS
.B tc qdisc ... dev
dev
.B  ( parent
classid 
.B | root) [ handle 
major: 
.B ] psp [ default 
minor-id
.B ] [ rate
rate
.B ] 

.B tc class ... dev
dev
.B parent 
major:[minor]
.B [ classid 
major:minor
.B ] psp rate
rate
.B ] [ mode 
mode
.B ] 

.SH DESCRIPTION
Precise Software Pacer (PSPacer) is a classful queuing discipline 
which controls traffic with
.BR tc (8)
command.
PSP achieves a precise pacing per class.

.SH GAP PACKET
The key to realizing precise pacing is to control the starting time of 
the transmission of each packet.  We propose a simple yet accurate 
mechanism to trigger the transmission of a packet.  That is, to insert 
a gap packet between the real packets.  The gap packet produces a gap 
between sequentially transmitted real packets.
We employ a PAUSE packet as a gap packet.  A PAUSE packet is defined in 
the IEEE 802.3x flow control.

By changing the gap packet size, the starting time of 
the next real packet transmission can be precisely controlled.
For example, to control a half rate transmission, a gap packet is inserted 
between every real packet where the gap packet size is the same as 
that of the real packets.

.SH IPG-AWARE SCHEDULING
Packet transmission is scheduled based on the IPG of each class
(i.e. target rate).
If the network has multiple bottleneck links, it is necessary to 
schedule the order of packet transmission and the packet interval.  

sch_psp maintains a virtual clock which is counted by the total transmitted 
byte instead of real time clock.  Each sub-class has its local clock 
which is used to make decision whether to send a packet or not.
If there is an idle time, a gap packet is inserted.

.SH CLASSIFICATION
Within one PSP instance, many classes may exist. Each of these classes
contains its own qdisc.

When enqueuing a packet, PSP starts at the root and uses various methods to 
determine which class should be used to obtain the data to be enqueued. 

In the standard configuration, this process is rather easy. 
At each node we look for an instruction, and then go to the class the 
instruction refers to. If the class found is a leaf-node (without 
children), we enqueue the packet there. If it is not yet a leaf node, we do 
the same thing over again starting from that node. 

The following actions are performed in order at each node we visit, until 
move to another node, or terminates the process.
.TP
(i)
Consult filters attached to the class. If we are at a leaf node, we are done. 
Otherwise, restart.
.TP
(ii)
If none of the above returned with an instruction, send to the default class.
.P
./ This algorithm makes sure that a packet always ends up somewhere, even while
./ you are busy building your configuration. 

.SH QDISC
The root of a PSP qdisc class tree has the following parameters:

.TP 
parent major:minor | root
This mandatory parameter determines the place of the PSP instance, 
either at the
.B root
of an interface or within an existing class.
.TP
handle major:
Like all other qdiscs, the PSP can be assigned a handle. It should consist only
of a major number, followed by a colon. Optional, but it is very useful 
if classes will be generated within this qdisc.
.TP 
default minor-id
Unclassified traffic is sent to the class with this minor-id.
.TP
rate rate
Optional.  You can explicitly specify the maximum transmission rate.
For example, if a 33MHz/32bit PCI bus is used to connect a Gigabit 
Ethernet network interface, the bottleneck is the PCI bus, and the 
system can not transmit packets at the rate of gigabit/sec. 

.SH CLASSES
Classes have a host of parameters to configure their operation.

.TP 
parent major:minor
Specifies the place of this class within the hierarchy. If attached directly 
to a qdisc and not to another class, minor can be omitted. Mandatory.
.TP 
classid major:minor
Like qdiscs, classes can be named. The major number must be equal to the
major number of the qdisc to which it belongs. Optional, but needed if this 
class is going to have children.
.TP 
rate rate
Maximum transmission rate this class including all its children are assigned. 
Optional, but required if this class is set to mode 1 (static target rate).
.TP
mode mode
Range from 0 to 2.  The mode 0 is without pacing.  The mode 1 is
pacing based on static target rate estimation.  And the mode 2 is 
pacing based on dynamic target rate estimation (TCP only, Future function).
Default is set to 0.

.SH EXAMPLE
The output bandwidth of eth0 regulates at 500Mbps:
.in +5
 # tc qdisc add dev eth0 root handle 1: psp default 1
 # tc class add dev eth0 parent 1: classid 1:1 psp rate 500mbit
 # tc qdisc add dev eth0 parent 1:1 handle 10: pfifo

.SH TODO
.TP
o
In the current version, the dynamic target rate estimation mode is disabled.
.TP
o
TCP Segmentation Offloading (TSO) feature is not supported.
You must disable TSO by ethtool:
.in +5
# /sbin/ethtool -K eth0 tso off

.SH SOURCES
.TP
o
http://www.gridmpi.org/
.TP
o
R.Takano, T.Kudoh, Y.Kodama, M.Matsuda, H.Tezuka, and Y.Ishikawa,
"Design and Evaluation of Precise Software Pacing Mechanisms for 
Fast Long-Distance Networks," PFLDnet05, 2005.

.SH SEE ALSO
.BR tc (8)

.SH AUTHOR
Ryousei Takano <takano-ryousei@aist.go.jp>.
